Structure uio

Structure uio_t

The uio_t structure describes data transfer for a character device:

The pfxread() and pfxwrite() entry points receive a uio_t that describes the buffer of data.
Within an pfxioctl() entry point, you might construct a uio_t to represent data transfer for control purposes.
In a hybrid character/block driver, the physiock() function translates a uio_t into a buf_t for use by the pfxstrategy() entry point.

The fields and values in a uio_t are declared in sys/uio.h, which is included by sys/ddi.h. For a detailed discussion, see the uio(D4) reference page. Typically the contents of the uio_t reflect the buffer areas that were passed to a read(), readv(), write(), or writev() call (see the read(2) and write(2) reference pages).

Data Location and the iovec_t

One uio_t describes data transfer to or from a single address space, either the address space of a user process or the kernel address space. The address space is indicated by a flag value, either UIO_USERSPACE or UIO_SYSSPACE, in the uio_segflg field.

The total number of bytes remaining to be transferred is given in field uio_resid. Initially this is the total requested transfer size.

Although the transfer is to a single address space, it can be directed to multiple segments of data within the address space. Each segment of data is described by a structure of type iovec_t. An iovec_t contains the virtual address and length of one segment of memory.

The number of segments is given in field uio_iovcnt. The field uio_iov points to the first iovec_t in an array of iovec_t structures, each describing one segment. of data. The total size in uio_resid is the sum of the segment sizes.

For a simple data transfer, uio_iovcnt contains 1, and uio_iov points to a single iovec_t describing a buffer of 1 or more bytes. For a complicated transfer, the uio_t might describe a number of scattered segments of data. Such transfers can arise in a network driver where multiple layers of message header data are added to a message at different levels of the software.

Use of the uio_t

In the pfxread() and pfxwrite() entry points, you can test uio_segflag to see if the data is destined for user space or kernel space, and you can save the initial value of uio_resid as the requested length of the transfer.

In a character driver, you fetch or store data using functions that both use and modify the uio_t. These functions are listed under "Transferring Data Through a uio_t Object". When data is not immediately available, you should test for the FNDELAY or FNONBLOCK flags in uio_fmode, and return when either is set rather than sleeping.